MacFormat 1994 September

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1994 September / macformat-004.iso / Shareware City / Graphics / MacAnim_Viewer_1.0.1 Folder / File Formats ƒ / GL Docs < prev next >

Wrap

Text File | 1993-09-05 | 136.8 KB | 4,125 lines | [TEXT/KAHL]

search for ++-- to get to the start of each doc... ++--------------------------------------------------------------------- G R A S P GRAphical System for Presentation Another USEware product from: Microtex Industries, Inc. 2091 Business Center Drive Irvine, Ca. 92715 (714) 476-0777 (714) 545-8100 - PCPaint Picture Swap Line Current release number: 1.10* Current release date :05/86 GRASP - Table of Contents ========================= Overview of Product . . . . . . . . . . . . . . . . . . . . . 1 What is GRASP? . . . . . . . . . . . . . . . . . . . . . 3 What is on the GRASP disk? . . . . . . . . . . . . . . . 4 Making a working copy of the GRASP disk . . . . . . . . 6 Installing GRASP . . . . . . . . . . . . . . . . . . . . 7 GRASP Installation Diagram . . . . . . . . . . . . . . . 8 How do I use GRASP? . . . . . . . . . . . . . . . . . . 9 Running GRASP . . . . . . . . . . . . . . . . . . . . . 10 The Grasp Editor . . . . . . . . . . . . . . . . . . . . 12 Simple GRASP Tutorial . . . . . . . . . . . . . . . . . 15 Running the library file version - GRASPRT . . . . . . . 18 Using the GRASP Graphics Librarian - GLIB . . . . . . . 19 The commands of GRASP - Detailed . . . . . . . . . . . . . . 21 BOX . . . . . . . . . . . . . . . . . . . . . . . . . . 23 CFADE . . . . . . . . . . . . . . . . . . . . . . . . . 24 CFREE . . . . . . . . . . . . . . . . . . . . . . . . . 25 CHGCOLOR . . . . . . . . . . . . . . . . . . . . . . . . 26 CIRCLE . . . . . . . . . . . . . . . . . . . . . . . . . 27 CLEARSCR . . . . . . . . . . . . . . . . . . . . . . . . 28 CLOAD . . . . . . . . . . . . . . . . . . . . . . . . . 29 COLOR . . . . . . . . . . . . . . . . . . . . . . . . . 30 EXEC . . . . . . . . . . . . . . . . . . . . . . . . . . 31 EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . 32 FFREE . . . . . . . . . . . . . . . . . . . . . . . . . 33 FGAPS . . . . . . . . . . . . . . . . . . . . . . . . . 34 FLOAD . . . . . . . . . . . . . . . . . . . . . . . . . 35 FLOAT . . . . . . . . . . . . . . . . . . . . . . . . . 36 FLY . . . . . . . . . . . . . . . . . . . . . . . . . . 37 FSTYLE . . . . . . . . . . . . . . . . . . . . . . . . . 38 GOSUB . . . . . . . . . . . . . . . . . . . . . . . . . 39 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . 40 IFKEY . . . . . . . . . . . . . . . . . . . . . . . . . 41 LINE . . . . . . . . . . . . . . . . . . . . . . . . . 42 LINK . . . . . . . . . . . . . . . . . . . . . . . . . . 43 LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . 44 MARK . . . . . . . . . . . . . . . . . . . . . . . . . . 45 MODE . . . . . . . . . . . . . . . . . . . . . . . . . . 46 NOISE . . . . . . . . . . . . . . . . . . . . . . . . . 48 OFFSET . . . . . . . . . . . . . . . . . . . . . . . . . 49 PALETTE . . . . . . . . . . . . . . . . . . . . . . . . 50 PAN . . . . . . . . . . . . . . . . . . . . . . . . . . 51 PFADE . . . . . . . . . . . . . . . . . . . . . . . . . 52 PFREE . . . . . . . . . . . . . . . . . . . . . . . . . 53 PLOAD . . . . . . . . . . . . . . . . . . . . . . . . . 54 POINT . . . . . . . . . . . . . . . . . . . . . . . . . 55 PUTUP . . . . . . . . . . . . . . . . . . . . . . . . . 56 RESETSCR . . . . . . . . . . . . . . . . . . . . . . . . 57 RETURN . . . . . . . . . . . . . . . . . . . . . . . . . 58 SETCOLOR . . . . . . . . . . . . . . . . . . . . . . . . 59 TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . 60 TRAN . . . . . . . . . . . . . . . . . . . . . . . . . . 61 VIDEO . . . . . . . . . . . . . . . . . . . . . . . . . 62 WAITKEY . . . . . . . . . . . . . . . . . . . . . . . . 64 WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . 65 Tips, Hints, Examples and Demo Programs . . . . . . . . . . . 67 Example Program #1 - Slide Show . . . . . . . . . . . . 69 Example Program #2 - How to animate using FLY . . . . . 70 APPENDIX A - Command Summary . . . . . . . . . . . . . . . . 71 APPENDIX B - Fade Table . . . . . . . . . . . . . . . . . . . 73 APPENDIX C - Error Messages . . . . . . . . . . . . . . . . . 75 APPENDIX D - Picture Swap Line . . . . . . . . . . . . . . . 79 APPENDIX E - GRASP Order Form . . . . . . . . . . . . . . . . 81 Overview of Product What is GRASP? GRASP is a simple graphics programming pseudo-language which can be used to create and run animated graphics demonstrations, tutorials, and presentations on an IBM PC/XT/AT or respective compatible. GRASP requires that the user make use of some other tool, such as Mouse Systems' PCPAINT PLUS, to create PCPAINT PLUS packed page or BSAVE format pictures, or 'capture' screens from any other graphics software with the provided capture utility program. This product was developed by the folks at Microtex Industries, the authors of PCPAINT PLUS, so it is patterned to take advantage of the pictures, clippings and fonts created with PCPAINT PLUS and its related utilities, like FONTASIA and ARTOOLS. Features: * Supports IBM CGA, IBM EGA, HERCULES, AST ColorGraphPlus, Plantronics, AST Preview, 3 text modes. * 16 Picture Buffers * 128 Clipping Buffers * Single command to control animation sequences * 25 different fades with limitless combinations * Simple ASCII file format * FONTRIX(tm) font compatible * Fully PCPAINT PLUS from MOUSE SYSTEMS(tm) compatible * Run Custom Programs from within GRASP program What is on the GRASP disk? The following files are on the GRASP disk GRASP.EXE - This is the main GRASP program. This version of GRASP gets the pictures, character sets, clippings and text files it needs from the current directory on your current disk drive, unless otherwise specified in the text files. This program allows you to create, edit and execute your GRASP programs. GRASPRT.EXE - This is the run-time version of GRASP. This version of GRASP gets the pictures, character sets, clippings, and text it needs from a graphics library created with the GRASP graphics librarian GLIB. This version only allows you to execute completed programs that are in library form. No editing of the files is possible. This .EXE file, along with your .GL file, may be distributed without license fees or other compensation. GLIB.COM - Library manager for version GRASPRT of GRASP product. Allows management of all necessary files in a library environment rather than as files in a subdirectory on a disk. WHATPIC.EXE - Utility program to determine size and color combinations of PCPAINT PLUS pictures. WHATCLP.EXE - Utility program to determine size and color combinations of PCPAINT PLUS clippings. CAP.COM - Capture Program for capturing screens and clippings from all your favorite software. STENCIL.SET - OLDTIME.SET - ROMAN.SET - PIGFONT.SET - DOTTIE.SET - Some fonts for you to use in your demo. ED1.HLP - CM1.HLP - CM2.HLP - CM3.HLP - FD1.HLP - FD2.HLP - RP1.HLP - Various help files. Making a working copy of the GRASP disk The GRASP disk is not copy protected in any way. You should back up the disk using the DOS diskcopy command, or you may perform a file by file backup to a hard disk using the DOS copy command. There are several different ways to copy disks under DOS, but the following will work on almost any hardware configuration since all it requires is access to the DOS master disk and 1 floppy disk drive. For PCs with 1 or 2 floppys, or an XT or AT with 1 floppy: Put your DOS master disk in drive A and turn on the machine or press CTRL-ALT-DEL to re-boot the system. Enter the Date and Time when prompted and you should see the system prompt: A>_ Type: A>DISKCOPY A: A: and press the return key. You will be prompted to put the SOURCE disk in drive A. Remove the DOS master disk from drive A, put the GRASP distribution disk in, close the door and press the return key. After it reads some information, DOS will ask you to put the TARGET disk in drive A. Put a blank disk (formatted or unformatted) into drive A, close the door and press return. If your machine has less than 512K of memory, you may be prompted to perform this disk exchange several times. When the process is complete, put the GRASP disk away in a safe place and use the backup copy for your work. Installing GRASP Simple Set-Up ------------- To develop demos under the grasp system, you need to have the following GRASP files and programs accessible: GRASP.EXE CM1.HLP CM2.HLP ED1.HLP FD1.HLP FD2.HLP RP1.HLP as well as your pictures, clippings and fonts. With all of these files in one subdirectory, you will be able to create and edit your demo program and have access to the help. If you do not need the help files, you may omit them. If you are going to be creating a library version of your demo, you will also need access to the librarian utility, GLIB.EXE. Advanced Set-Up --------------- The following is an example of a well set-up system on a hard disk, including PCPAINT, so that you can edit pictures and clippings and create your demo with a minimum of effort. From the root directory, create a sub-directory called PAINTLIB and put all the PCPAINT files in it. (This is the recommended method for installing PCPAINT). In addition, be sure your PATH statement points to PAINTLIB and set up an environment variable to point to PAINTLIB as well with the command: SET PAINTLIB=C:\PAINTLIB Also make a sub-directory off the root called GRASP. Copy the GRASP disk contents to the sub-directory GRASP. Add the GRASP directory to your PATH command. Then create a DEMO directory, change to it, and run GRASP by typing GRASP at the command prompt. When you are in the GRASP editor, you can run PCPAINT by pressing ALT-F10 and your previous PATH and SET statements will help DOS know where to find it. The following diagram is an example: GRASP Installation Diagram This diagram shows the proper structure for your sub-directories for GRASP to perform in the above stated manner. This is not a requirement, just an example. ___________ | | | C:\Root | |___________| ________________________|________________________ . . . . ______|_______ ______|______ __________|__________ | | | | | | | PAINTLIB | | GRASP | | DOS or OTHER | |______________| |_____________| |_____________________| : : | : PCPAINT.EXE GRASP.EXE | DOS files PxPAINT.OVR ED1.HLP | Various batch files CAP.COM CM1.HLP | CM2.HLP | CM3.HLP | FD1.HLP | FD2.HLP | RP1.HLP | | ___________|_ | | | Demos | |_____________| Then these statements would be in your AUTOEXEC.BAT file: SET PAINTLIB=C:\PAINTLIB PATH C:\PAINTLIB;C:\GRASP;C:\whateverelseyouwant... With this set-up, you can be in any directory and run GRASP by typing GRASP and PCPAINT by typing PCPAINT. You have full access to all help files and the PCPAINT system. The auto-run feature in GRASP (ALT-F10) allows you to run PCPAINT while in GRASP. It looks for PCPAINT in the \PAINTLIB directory. The GRASP help files are only accessible if they are in one of three places: 1) In the current directory 2) In the directory pointed to by the environment string 'PAINTLIB' 3) In a sub-directory off the root called 'GRASP' GRASP performs a search for the help files in this order. If they are not found, a message will appear when you first run grasp telling you so. You may run GRASP without access to the help files, but you will get a beep if you try to access them. How do I use GRASP? To use GRASP you need to do 3 things. 1) Create the pictures and clippings you want to use with PCPAINT PLUS, or capture them the the CAP utility. 2) Use the built-in GRASP editor to create an GRASP 'program' which is nothing more than a list of GRASP commands and some comments. 3) Run your demonstration by pressing F10 from the editor or by selecting EXECUTE FILE from the main GRASP menu. It's that simple. If you want to give your demo away, you must put the .PIC, .CLP, .SET and .TXT files into a library with the GLIB utility, and distribute the library file with GRASPRT.EXE. Running GRASP To run the GRASP, enter at the command prompt: A:>GRASP You will be presented with a screen that looks something like this: G R A S P GRAphical System for Presentation Version 1.10* - May, 1986 Copyright (C) 1986 - Microtex Industries, Inc. Edit File Execute File Load File Save File Quit GRASP Current File: TMPFILE To select an option from this menu, use the up and down arrow keys until the option you want to select is highlighted. Then just press return and the option is selected. Each of these options has a special meaning to GRASP. Edit File: The Edit File option tells GRASP that you want to go to the editor and create or modify your GRASP program file. Execute File: The Execute File option tells GRASP to execute the currently loaded GRASP program file. Load File: The Load File option allows you to tell GRASP to load in an existing file, or to create a new one. Notice that just below the menu there is an area with the current filename listed. When you first run GRASP, the system will default to a file named TMPFILE. This is the name that GRASP will use unless you specify a new one. To specify a new one, just type in the name you want. DO NOT specify the filename extension. GRASP will automatically use the extension .TXT for you. To create a new file, just perform the load as though the file you want already exists. GRASP is smart enough to understand and create a new file for you. If a file is already loaded, and changes have been made, GRASP will prompt you for saving before allowing you to load another. This keeps you from trashing your current file. Save File: The Save File option tells GRASP that you want to save the current working GRASP program file. It works much the same as the load command. Just specify the name you want to save the file under and press return. The system will default to the current working name. Quit GRASP: The Quit GRASP option tells the system that you want to exit GRASP. If a file is loaded and has been changed since the last save, GRASP will prompt you for saving before allowing you to quit. Be sure to save your file before quitting! Of these options, the only one that requires special consideration is the first one, Edit File. Select that option and let's explore the world of the GRASP editor... The Grasp Editor If you have selected the Edit File option from the main menu, you will now be in the GRASP editor. The screen should have a blue line across the top that looks like the following: TMPFILE COL:1 LINE:1 POS:0 LEN:0 INSERT ON These are just information items about the current file you are working on and the mode you are operating in. Starting at the left is the name of the current file, which defaults to TMPFILE. Next comes the current cursor column number, the current cursor line number, the current cursor's character position relative to the entire file, and the total number of characters in the current file. At the far right is the status of the INS key on your keyboard. If INSERT mode is ON, then characters you type will be inserted before the character just to the right of the cursor. If INSERT mode is OFF, then characters to the right of the cursor will be overwritten. This second mode, INSERT OFF, is commonly called OVERSTRIKE mode. This information is just there for reference, and with the exception of the INSERT mode signal, you probably won't need to refer to it too often. The first three function keys are the most important keys to learn in the GRASP editor. GRASP provides 'Quick Help' for three different areas and is accessable by pressing F1, F2 or F3. NOTE: If you press one of these function keys and hear a low tone from your computer and no help appears, it means that GRASP couldn't find the .HLP files that were on your distribution disk. If you want to use the help. the .HLP files must be on the current drive and directory, in a directory called 'GRASP' directly off the root directory, or in a directory pointed to by the environment string 'PAINTLIB'. See INSTALLING GRASP for more details. F1 - Provides help in using the GRASP Editor. This includes a list of the most commonly used editing keys and a description of what each function key is used for. F2 - Provides a quick summary listing of all available GRASP commands. This information is not a complete reference on the commands of GRASP, but rather a command syntax reference so that you can insure proper useage of the commands and a brief description of what the command is used for. F3 - Provides a summary listing of the 25 GRASP fades and their respective numbers. Remember that all fades can be used for graphics pictures, text pictures, pictures in a window and clippings. If this is your first time running GRASP and you are too lazy or too bored to read the entire manual, you should find enough information in these help keys to get you started. If you want to learn a little more about the editor, here is a full description of all the keys available in the GRASP editor. F1 - Quick help with the editor. F2 - Quick help with the commands. F3 - Quick help with the fades and video modes. F4 - Start/End highlighting a block. F5 - Copy a highlighted block. F6 - Move a highlighted block. F7 - Read a block in from disk. F8 - Write a highlighted block to disk. F9 - Save current file and run from current line. F10 - Save current file and run from the top. ALT/F1 - Quick exit to DOS. Typing EXIT at the DOS propmt returns you to the GRASP editor. ALT/F10 - Run PCPAINT from within the GRASP editor. PCPAINT.EXE and its overlays must be in a subdirectory called PAINTLIB off the root directory on the current drive. CTRL-K-X or ESC - Quit the editor. Do not save file. Leave flag set that indicates changes if they have been made. CTRL-K-Q - Quit the editor. Do not save file. Reset flag to indicate no changes have been made. CTRL-K-D or ALT/X - Quit the editor, save file if changes have been made. CTRL-K-S or ALT/S or ALT/W - Save the current file and continue editing. ALT/L or ALT/R - Reload the current file and continue editing, overwriting any changes made. CTRL-Y or ALT/D - Delete current line. CTRL-N - Insert a carriage return and leave cursor at current line. CTRL-K-B - Mark block beginnng. Same as the first time you hit F4. CTRL-K-K - Mark block end. Same as the second time you hit F4. CTRL-Q-B - Go to block beginning. CTRL-Q-K - Go to block end. CTRL-K-C - Copy a block. Same as F5. CTRL-K-V - Move a block. Same as F6. CTRL-K-R - Read block at cursor position. Same as F7. CTRL-K-W - Write block. Same as F8. CTRL-K-Y - Delete highlighted block. CTRL-HOME or CTRL-Q-R - Go to top of file. CTRL-END or CTRL-Q-C - Go to end of file. CTRL-RIGHT ARROW or CTRL-F - Skip word right. CTRL-LEFT ARROW or CTRL-A - Skip word left. CTRL-Q-S or HOME - Go to beginning of line. CTRL-Q-D or END - Go to end of line. INS - Turns insert mode on and off. DEL - Deletes character under cursor and adjusts text. ARROW KEYS / PGUP / PGDN and Wordstar(tm) 'Diamond' equivalents move cursor around document. Now that you know how to use the editor, let's see exactly how to make a demo... Simple GRASP Tutorial Loading and displaying a picture: It is important to understand that GRASP is very much a LINE oriented programming pseudo-language. It is called this because inter-line dependencies have been kept to a minimum. In simpler terms, GRASP interprets one line at a time, executes it, then goes and gets the next line. Except for a few special cases, what happens on each line is relatively independent of the previous line or the next line. This is important because if you understand this, then creating a GRASP program will be easier to understand in concept. Each line can start with only one of three things: 1) A GRASP command. (PRESS F2 to see all the GRASP commands) 2) A semicolon - ';'. This indicates the beginning of a comment. 3) A label. This can be any continuous string of ASCII characters with the exception of space, and must be followed by a colon - ':'. This keeps the GRASP interpreter's job simple. It either sees a command, and immediately looks for possible parameters, or a semicolon, in which case it ignores the rest of that line, or a label, which it puts into a list so it can find it later if needed. Any variation from these three options will result in GRASP thinking that what you typed was a GRASP command which it cannot understand, and results in an 'INVALID COMMAND IN LINE XXX' message when you try to execute the program. Usually, you will want to start you GRASP program with a comment, like a title of your program or your name, etc. Type: ; DEMO Program for GRASP and press return. You now have written a 1-line GRASP program. Exciting huh? I'll bet you can't wait for more. The very first command in every GRASP program should be a VIDEO command which tells GRASP which video mode you want to use. If you select a video mode that is not available on your computer, GRASP will try to understand and tell you so. If you get wierd results, or the screen seems to go crazy, don't worry, just check the reference section of this manual to be sure you are using a valid video mode. For this tutorial, we will assume that your computer has an IBM Color Graphics Adapter or compatible, and we will use the standard 4 color 320x200 mode, which GRASP understands as video mode A. Type the following (exactly as spelled below, with upper case): ; DEMO Program for GRASP ; video Q Now press F10 to execute the program. (By the way, all this does is set the video mode and come back to the editor. Not too exciting yet, but we're getting there...) You should get a message that says Illegal argument(s) at line 3 File TMPFILE.TXT Press any Key to Continue Any time you see the message, it means that the command you entered was correct, but one of the arguments you entered was incorrect. Press a key and you will be returned back to the editor, to the line where the error occured. The problem here is that Q is an invalid video mode. Change it to A (which stands for CGA 320x200 4 color mode) and press F10 again. Your screen should blink and the you will be put back in the editor. Now we have named the program and set up a video mode, so it's time to try out some graphics commands. On the distribution disk is a picture named GRASP.PIC. This is a 4 color picture from the CGADEMO.GL file. Let's load it into GRASP and display it using a variety of fades. ; DEMO Program for GRASP ; video A ; pload grasp,1 ; load picture into buffer #1 pfade 0,1,0,0 ; fade it to the screen using fade ; #0 waitkey ; wait for a keypress before ; returning to the editor. now, press F10 and you should see the GRASP.PIC picture loaded and displayed. Change the first parameter of the pfade command to any number between 0 and 25 and watch all the different special effects. Then to slow things down, try a number like 50 for the third parameter, which is the speed of the fade. Speed seems to have no effect on some fades, while on others, it makes a lot of difference. This is because of the nature of each individual fade. To optimize the performance of GRASP, it was decided that speed would be a relative number, that is, relative to the actual fade. This way, each fade may be accurately controlled from its fastest speed to its slowest. Let's do one more command, the WINDOW command. Window means don't allow any part of the picture that lies outside of a specific rectangle to be faded to the screen. Add the window command to your demo program as follows: ; DEMO Program for GRASP ; video A ; pload grasp,1 ; load picture into buffer #1 window 0,0,100,100 ; set fade clip window pfade 0,1,0,0 ; fade it to the screen using fade ; #0 waitkey ; wait for a keypress before ; returning to the editor. now press F10 and watch the difference. You should see that only the lower left part of your picture was actually dissolved to the screen. Change the coordinates of the window command and watch the results. One other note: The window command can only operate on byte boundaries. For most video modes, this means every 8 pixels in the x direction. You don't have to worry because WINDOW will automatically adjust itself to a byte boundary. This concludes this lesson. Other commands in GRASP work in a similar fashion. Experiment with them. Just remember to keep track of your video modes and buffers. You may also want to take apart the demo program, CGADEMO.GL using the GLIB.EXE utility and look at the code for more examples. Running the library file version - GRASPRT The Library file, or runtime version of the program is identical to the text file version except that the interpreter gets its information from a library file instead of the current disk and directory. The GLIB utility will put all of your .PIC, .CLP, .SET and .TXT files into a library with the extension GL. To run your demo execute the command: GRASPRT <libfile> <textfile> If the textfile is omitted from the command line, GRASP will execute the first text file it finds in the library. To run the demo that comes with GRASP, type: GRASPRT CGADEMO Using the GRASP Graphics Librarian - GLIB The Graphics LIBrarian, GLIB.EXE, is used in the following manner: GLIB [-dstuea] libname [files...] where the following commands are supported: -d delete file from library -s extended file list -t quick file list -u update (add) file to library -e extract file from library -a extract all files from library For example, if you wanted to put all of the .PIC files in the current directory into a library file named MYFILE, you would type: GLIB -u MYFILE *.PIC Or if you wanted to extract GRASP.PIC from the library CGADEMO, you would type: GLIB -e CGADEMO GRASP.PIC Be sure that all files needed for your demo are in the library file before you try to run it. Otherwise, you may get error messages. NOTE: You cannot use wild cards for extracting or deleting in this version (1.0) of GLIB. However, you may use wild cards for adding to or updating the library. More Examples: GLIB -d DEMO FRED.TXT will delete the file 'fred.txt' from library file DEMO.GL GLIB -e DEMO LOGO.CLP will extract the clipping 'logo.clp' from library file DEMO.GL GLIB -u DEMO MTX.CLP will add/replace the picture 'mtx.pic' to library file DEMO.GL The commands of GRASP - Detailed BOX BOX Summary: ------- BOX allows you to draw a box on the screen in the current drawing color. Syntax: ------ BOX startx, starty, endx, endy, <width> where 'startx' and 'starty' is the point of one corner of the box and 'endx' and endy' is the point of the opposite corner of the box. Width is the number of pixels wide you want the box to be. Width is drawn 'inward' from the original box. Example: ------- BOX 0,0,100,100 will draw a box in the current drawing color from x=0, y=0 to x=100, y=100. Comments: -------- Transparent mode does not affect this command. Default width is 1. BOX is not available in text modes. CFADE CFADE Summary: ------- CFADE allows you to dissolve or fade a clipping to the screen. You may specify one of several dissolves, the speed for that dissolve, and a delay after the dissolve. This command is similar to PFADE, but applies to clippings. The same 25 fades that apply to pictures also apply to clippings. Syntax: ------ CFADE fade number, x, y, <buffer number>, <speed>, <delay> where 'fade number' is the number of the fade you want to use, 'buffer number' is the clipping buffer number where the clipping you want to fade has been loaded, 'x' and 'y' are the location for the clipping to be faded, 'speed' is the speed of the fade and 'delay' is the time to wait after the delay. Speed can be in the range 0-10000. Check Appendix B for a list of fades. Example: ------- CFADE 2,20,40,5,500,1000 will fade the clipping in buffer 5 using fade 2 at location x=24, y=40 at speed 500, and then wait 10 seconds. The delay works the same as using the WAITKEY command. Comments: -------- Note: CFADE only fades byte-width clippings and puts them up at the nearest byte boundary to the x and y specified in the command. Deviations may cause unpredictable results. Use the utility WHATCLP to obtain the needed information about your clippings. If your clipping is not byte-width, it will fill the right edge to byte-width with white (highest color available). Transparent mode does NOT apply to CFADE. Default values for optional parameters: buffer number: 1 speed: 0 delay: 0 CFREE CFREE Summary: ------- CFREE is used to free-up a clipping buffer. Sometimes, you may run out of memory and need to clear up some buffers you have full of clippings you have already used. Syntax: ------ CFREE buf1, <buf2>, <buf3>... where 'buf1' and other buffers are buffers you want to free-up. Example: ------- CFREE 1,4,12 will free-up clipping buffers 1, 4 and 12. CFREE 1,-,16 will free-up buffers 1 through 16. You MUST use commas or spaces to separate these parameters. Comments: -------- This is especially useful in EGA 16 color mode where space is critical. CHGCOLOR CHGCOLOR Summary: ------- Chgcolor is used to set the color palette registers in IBM EGA 16 color mode. On the EGA, there are 16 possible colors, called an 'index', and each of these color indices may be one of 64 color 'values'. Syntax: ------ CHGCOLOR color index, color value,... where 'color index' refers to the color number you want to change in the range 0-15 and 'color value' lies in the range 0-63. Example: ------- CHGCOLOR 3,32 will change color index 3 to color value 32. Comments: -------- Remember, this only works in EGA 16 color modes. CIRCLE CIRCLE Summary: ------- CIRCLE allows you to draw a circle or ellipse on the screen in the current drawing color. The color parameters must be specified in pairs, as in the example. Syntax: ------ CIRCLE centerx, centery, xradius, <yradius> where 'centerx' and 'centery' is the center point of the circle or ellipse, xradius' is the radius in the x-direction and 'yradius' is the radius in the y direction. Example: ------- CIRCLE 100,100,100,20 will draw a circle centered at x=100, y=100 with x radius=100 and y radius=20. Comments: -------- Transparent mode does not affect this command. Failure to specify a yradius assumes yradius=xradius and a circle is produced. Note also that circle here implies xradius=yradius which, depending on the aspect ratio of your current video mode, may not be a circle. CIRCLE is not available in text modes. CLEARSCR CLEARSCR Summary: ------- Clearscr is used to clear the screen to the current drawing color. Syntax: ------ CLEARSCR Example: ------- CLEARSCR will clear the screen to the current drawing color (the color set with the last COLOR command). Comments: -------- CLOAD CLOAD Summary: ------- This command is used to load a clipping into a buffer. There are 128 buffers available for clippings in GRASP. It is advised, for memory reasons, that the user try to manage using as few as possible. A clipping must be loaded into a buffer before it can be dissolved or put up onto the screen. Syntax: ------ CLOAD clipping, buffer number, <shiftparm> where 'clipping' is the name of the clipping you want to load (the file name extension is optional) and 'buffer number' is the number of the buffer you want to load in to. Valid buffer numbers are 1 through 128. Buffer 0 is non-existent for clippings, and thus, no clipping may be loaded into it. 'Shiftparm' indicates whether or not to create the shifted copies necessary to place clippings at non-byte boundaries. Default for shiftparm is 0 or YES. Placing a 1 here will cause GRASP not to create the shifted copies and thus saving memory. This is useful if you know that you are going to be using CFADE on this clipping and therefore couldn't use the shifted copies anyway. Example: ------- CLOAD myclip,5 will load the clipping myclip.clp into clipping buffer number 5. Comments: -------- If you do not understand the concept of shifted copies, it is best not to fool around with the shiftparm parameter. Note also that a file extension is not necessary in your GRASP file. Drive letter and path may be specified. COLOR COLOR Summary: ------- COLOR allows you to choose a drawing color. Drawing color is used for drawing primitives (such as line, box, circle, or point), transparent mode selection, text strings and clearing the screen. Secondary color is used for background color in text mode or shadow color for font styles in graphics modes. Syntax: ------ COLOR n1,<n2> where 'n1' is the drawing color and 'n2' is the secondary color. Example: ------- COLOR 3,0 will set the current drawing color to color 3 and the secondary color to 0. Comments: -------- Related commands are LINE, BOX, CIRCLE, POINT, TRAN, CLEARSCR, PALETTE, MODE and PFADE. The secondary color is used for the bottom character in shadow text strings and the background color for text screens. Secondary color defaults to color 0 if not specified. EXEC EXEC Summary: ------- This command allows you to execute another program from within your GRASP program. Useful for utility programs, or custom programs you write that provide a function that GRASP does not. Syntax: ------ EXEC program, <parameters> where 'program' is the name of the program you wish to execute. You MUST include path if it is in a different path, and all program names must include the extension. 'Parameters' are any command line parameters you would normally pass to the program. Example: ------- EXEC \PAINTLIB\PCPAINT.EXE, /O will execute pcpaint from the \paintlib directory on the current drive passing the /O parameter. Comments: -------- You MUST include full path and file extension. EXIT EXIT Summary: -------- Exit will cause the currently running GRASP program to quit and return to DOS or the GRASP editor. Syntax: ------ EXIT Example: ------- EXIT will cause the currently running GRASP program to terminate and return to DOS or the GRASP editor. Comments: -------- If you are running GRASPRT, EXIT returns you to DOS. If you are running GRASP, EXIT returns you to the editor or the main menu, depending on how you ran the program. FFREE FFREE Summary: ------- This command will free up the font buffer so that more memory may be available for pictures and clippings. Syntax: ------ FFREE Example: ------- FFREE will free up the font buffer. Comments: -------- FGAPS FGAPS Summary: ------- This command allows you to set the gaps between characters in the text command and also the width of the space character. Syntax: ------ FGAPS <char gap, space gap> where 'char gap is the number of pixels between characters and 'space gap' is the number of pixels wide for the space character. Example: ------- FGAPS 3,9 will set the inter-character gap to 3 pixels and the space character to a width of 9 pixels. Comments: -------- Note that this has no effect on the TEXT command if you are in TEXT mode. FGAPS with no parameters resets the gaps to the default gaps for the currently loaded font. FLOAD FLOAD Summary: ------- This command is used to load in a character set. The GRASP system only allows 1 character set in memory at a time. After a character set has been loaded, TEXT commands (see command TEXT) will be performed using the currently loaded font. Applies only to graphics modes. Syntax: ------ FLOAD fontname where 'fontname' is the name of the FONTRIX(tm) or PCPAINT font file you wish to load. File name extensions are optional. Example: ------- FLOAD bocklin will load the FONTRIX(tm) font bocklin.set into memory for use by the TEXT command. Comments: -------- When a font is loaded with FLOAD, the gaps are reset to the default gaps for that font. So be sure to reset gaps using the FGAPS command if the default gaps aren't adequate. FLOAT FLOAT Summary: ------- FLOAT allows you to animate a clipping or series of clippings between any two points on the screen with one command. It is similar to FLY except that it performs an exchange with screen data so that the background may be preserved. Syntax: ------ FLOAT startx, starty, endx, endy, increment, delay, clip1, clip2, ...clipn where 'startx' and 'starty' indicate the starting point, 'endx' and 'endy' indicate the ending point, 'increment' is the distance between each put along the line, 'delay' is the wait time between each put and 'clip1-clipn' is the list of clippings. Example: ------- FLOAT 0,0,200,200,2,10,1,2,3 will 'FLOAT' the clippings 1,2 and 3 in that order from 0,0 to 200,200, skipping 2 pixels between each put, waiting a count of 10 between each put. For example, clip 1 will be put at 0,0, clip 2 will be put at clip 2,2, clip 3 will be put a 4,4, clip 1 will be put at 6,6, clip2 will be put at 8,8, etc. Comments: -------- This command differs from FLY in that it preserves the background. Also note that the last operation it performs is the swap-back, which restores screen data. This means that if you want to have a clipping on the screen after the FLOAT command, you have to follow the FLOAT with a PUTUP command. Selective use of transparent can yield very interesting results. FLY FLY Summary: ------- FLY allows you to animate a clipping or series of clippings between any two points on the screen with one command. Syntax: ------ FLY startx, starty, endx, endy, increment, delay, clip1, clip2, ...clipn where 'startx' and 'starty' indicate the starting point, 'endx' and 'endy' indicate the ending point, 'increment' is the distance between each put along the line, 'delay' is the wait time between each put and 'clip1-clipn' is the list of clippings. You may animate up to 10 clippings. Example: ------- FLY 0,0,200,200,2,10,1,2,3 will 'fly' the clippings 1,2 and 3 in that order from 0,0 to 200,200, skipping 2 pixels between each put, waiting a count of 10 between each put. For example, clip 1 will be put at 0,0, clip 2 will be put at clip 2,2, clip 3 will be put a 4,4, clip 1 will be put at 6,6, clip2 will be put at 8,8, etc. Comments: -------- Selective use of slightly larger than necessary clippings (to wipe out the previous put) and transparent mode can yield very interesting results. FSTYLE FSTYLE Summary: ------- This command allows you to choose a style for the characters in the TEXT command. Styles are as follows: style # style ------- ----- 0 Default, normal letters 1 Bold up. 2 Bold right. 3 Shadow up right. 4 Shadow up left. 5 Shadow up right 2 pixels. 6 Shadow up left 2 pixels. Syntax: ------ FSTYLE fstyle where fstyle is the number of the desired style. Example: ------- FSTYLE 4 will set the text style to shadow up left. Comments: -------- Use of the command with no parameters will default to style 0. GOSUB GOSUB Summary: ------- This command allows the transfer of control during execution of a GRASP program to a sub-program defined elsewhere in the program. This is similar to a BASIC gosub command. The subprogram is defined by a label at the beginning, and a RETURN command at the end. When the RETURN is encountered, control is returned to the line following the line where the GOSUB ocurred. Syntax: ------ GOSUB subroutine where 'subroutine' is a sub-program defined elsewhere in the GRASP program. Example: ------- GOSUB myprog will transfer control to the sub-program 'myprog'. Control will return when the statement RETURN in encountered in the sub-program. Comments: -------- Also see command RETURN. GOTO GOTO Summary: ------- This command allows you to transfer control of a GRASP program to another portion of the program, similar to the same command in BASIC. You must first define a label at the point you want to go to. Labels are defined as any string of less than 16 characters terminated by a colon (:). Syntax: ------ GOTO label where 'label' is defined somewhere else in the program. Example: ------- GOTO here will transfer control to the line which begins with the string 'here:'. There may only be one label of a particular name in one GRASP program. Comments: -------- You may have up to 512 labels in a GRASP program. IFKEY IFKEY Summary: ------- IFKEY allows conditional branching by means of an implied goto. If the key indicated in the command matches the last key pressed during a waitkey command, branching occurs. Syntax: ------ IFKEY key label where key is the key code to compare to and label is a label defined elsewhere in the program. Example: ------- IFKEY 1 part1 means that if, during the last waitkey command, the '1' key was pressed, goto label "PART1". Comments: -------- LINE LINE Summary: ------- LINE allows you to draw a single pixel width line on the screen in the current drawing color. Syntax: ------ LINE startx, starty, endx, endy where 'startx' and 'starty' is the location for the first point in the line and 'endx' and 'endy' is the location for the last point in the line. Example: ------- LINE 0,0,100,100 will draw a line in the current drawing color from x=0, y=0 to x=100, y=100. Comments: -------- Transparent mode does not affect this command. LINE is not available in text modes. LINK LINK Summary: ------- This command is used to link to another text command file. IF you wish to have several special effects, and for editing purposes, keep them is separate ASCII files, you may link them during GRASP run time with this command. Syntax: ------ LINK txtfile where 'txtfile' is the name of the command file you wish to execute. File name extensions are not required, but all text command files must have an extension of txt. Example: ------- LINK race will link to the text command file 'race.txt' and continue executing. Comments: -------- Since this command requires interpretation of the command itself, the loading of a new file, and the interpretation of the second file, it has a tendency to slow things down. It is recommended that all commands be put into one file before giving a presentation using GRASP. This command is useful during development, or if you have stored several effects from previous demonstrations and want to link them together. LOOP LOOP Summary: ------- This command causes the GRASP interpreter to loop back to the previous mark. This will happen n number of times, where n is the number specified in the previous MARK command. Syntax: ------ LOOP Example: ------- LOOP will loop to previous mark. Comments: -------- MARK/LOOP pairs may be nested up to 16 levels deep. MARK MARK Summary: ------- This command is used to mark a position which will be the top of a loop. Coupled with the LOOP command, MARK allows you to repeat the same steps in your GRASP command file a specified number of times. Syntax: ------ MARK xxx where 'xxx' is the number of times you wish to loop back to this mark. Example: ------- MARK 10 will place a mark at this point so that the next time a LOOP command is encountered, the program will loop back to this point. This process will occur ten times. Comments: -------- MARK/LOOP pairs may be nested up to 16 levels deep. The maximum number of times you can loop is 65535. MODE MODE Summary: ------- Mode is used in IBM CGA 4 color mode and IBM CGA 2 color mode only. It is used to set the palette and border color in these modes. Syntax: ------ MODE border color, palette where 'border color' refers to the background color in IBM CGA 4 color mode and foreground color in IBM CGA 2 color mode. 'Border color' can be in the range 0-15. Palette affects only IBM CGA 4 color mode and is in the range 0-5. Refer to the following tables for specifics. Border Color Table Color Color Palette 1 2 3 ----- ----- ------- ----------------------------------- 0 Black 0 Green Red Brown 1 Blue 1 Cyan Magenta White 2 Green 2 Cyan Red White 3 Cyan 3 Bright Green Bright Red Yellow 4 Red 4 Bright Cyan Bright Magenta White 5 Magenta 5 Bright Cyan Bright Red White 6 Brown ------------------------------------------- 7 Grey 8 Dark Grey (Bright Black) 9 Bright Blue 10 Bright Green 11 Bright Cyan 12 Bright Red 13 Bright Magenta 14 Yellow (Bright Brown) 15 White (Bright Grey) In the above Palette table, color 0 is the currently selected Border Color. Example: ------- Mode 1,4 will yield the following: (Assuming we are in IBM CGA 4 color mode), border color is blue (Drawing Color 0), and the palette will be bright cyan, bright magenta, and white. (Drawing colors 1,2 and 3, respectively) in IBM CGA 4 color mode. In IBM CGA 2 color mode, The foreground color will be blue. Comments: -------- This command was intended for use only in IBM CGA 4 color and IBM CGA 2 color modes. Use in any other mode may result in an error message. NOISE NOISE Summary: ------- NOISE allows you to make music in GRASP. By specifying starting and ending frequencies, as well as a duration, you can make single notes, or complex sounds. Syntax: ------ NOISE startfreq, endfreq, duration where 'startfreq' and 'startfreq' are the starting frequencies for the noise and 'duration' is the overall length of the noise. Example: ------- NOISE 440,440,100 will play the note with a frequency 440 for duration 100. Comments: -------- OFFSET OFFSET Summary: ------- The OFFSET command allows you to treat coordinates in other commands (like putup, line, box, cfade, etc...) as relative coordinates rather than absolute. If the OFFSET is set to 0,0, then the coordinates you enter in the other commands are relative to the screen as a whole which appears to be absolute. This command is used when you want to repeat a series of operations but don't want to have to alter all the coordinates in order to use a different region of the screen. Syntax: ------ OFFSET x,y where 'x' and 'y' are the x and y offset values. Example: ------- OFFSET 40,32 will set the offset to x=40, y=32. This means that if you specify that you want a line drawn from 0,0 to 10,10, it will actually draw it from 40,32 to 50,42. In other words, the offset values are added to the coordinate data you type in the command. Comments: -------- PALETTE PALETTE Summary: ------- Palette is used to set the current palette to that of the specified picture which has been loaded into a buffer. This sets the 16 colors out of 64 on EGA 16 color modes and the border-palette combination of CGA 4 color mode. Syntax: ------ PALETTE buffer number Where 'buffer number' is the number of the buffer in which the picture resides. Example: ------- PALETTE 2 will set the current palette to the palette used for the picture which was loaded into buffer 2 with the PLOAD command. Comments: -------- This command was intended for use in EGA 16 color mode and CGA 4 color mode only. Use in other modes may cause unpredictable results. Use with caution. PAN PAN Summary: ------- This command allows you to perform a hardware pan if you are operating in one of the EGA modes. If the picture you want to pan around on is larger than a screen then the following rules apply: 1) You MUST use PFADE number 0 to put up the picture, 2) when you are finished panning and scrolling, you MUST PFREE the picture, clear the screen with CLEARSCR, then do a RESETSCR before using any other pictures. This is so that the EGA will be able to keep track of which picture you are using and how to best display it. Also, sequences of PAN commands should always return you to the coordinate 0,0 when you are done. Think of the picture as being a very large screen with the upper left corner being coordinate 0,0. Pan then allows you to change upper left corner to be any coordinate in the valid coordinate space. Syntax: ------ PAN x0,y0,x1,y1,buffer where 'x0', 'y0' is the starting coordinate for panning and 'x1', 'y1' is the ending coordinate. 'Buffer' is the picture buffer that the command will look into to get real picture coordinates and set the EGA display modes to coincide to. Example: ------- PAN 0,0,100,100,1 PAN 100,100,0,0,1 will smoothly pan the screen diagonally from the upper left corner to 100,100 and back again. Comments: -------- This is a complicated command and requires some thought to use effectively. Be careful. CAUTION: It is imperative that you free the oversize picture buffer BEFORE you perform the CLEARSCR and RESETSCR functions! PFADE PFADE Summary: ------- Pfade is the heart of GRASP. It allows you to dissolve a picture to the screen. You may specify one of several dissolves, the speed for that dissolve, and a delay after the dissolve. Syntax: ------ PFADE fade number, buffer number, speed, delay where 'fade number' is the number of the fade you want to use, 'buffer number' is the picture buffer number where the picture you want to fade has been loaded, 'speed' is the speed of the fade and 'delay' is the time to wait after the delay. Speed can be in the range 0-10000. Check Appendix B for a list of fades. Example: ------- PFADE 12,1,500,1000 will fade the picture in buffer 1 using fade 12 at speed 500 and then wait 1000. The delay works the same as using the WAITKEY command. Comments: -------- The first 25 fades in GRASP are the same in all video modes. Fades beyond 25 may be mode specific and must be used with caution. Specifying buffer 0 will cause a blank screen of current drawing color to be generated and faded to the screen. Transparent mode does NOT apply to PFADE. PFREE PFREE Summary: ------- PFREE is used to free-up a picture buffer. Sometimes, you may run out of memory and need to clear up some buffers you have full of pictures you have already used. Syntax: ------ PFREE buf1, buf2, buf3... where 'buf1' and other buffers are buffers you want to free-up. Example: ------- PFREE 1,2 will free-up picture buffers 1 and 2. Comments: -------- This is especially useful in EGA 16 color mode where space is critical. PLOAD PLOAD Summary: ------- This command is used to load a picture into a buffer. There are 16 buffers available for pictures in GRASP. It is advised, for memory reasons, that the user try to manage using only one buffer. A picture must be loaded into a buffer before it can be dissolved onto the screen. Syntax: ------ PLOAD picture,buffer number where 'picture' is the name of the picture you want to load (the file name extension is optional) and 'buffer number' is the number of the buffer you want to load in to. Valid buffer numbers are 1 through 16. Buffer 0 is a dummy buffer used for solid color wipes and changes, and thus, no picture may be loaded into it. Example: ------- PLOAD mypic,1 will load the picture myfile.pic into picture buffer number 1. Comments: -------- POINT POINT Summary: ------- POINT allows you to draw a single pixel on the screen in the current drawing color. If a second point is indicated, a random point is drawn in the rectangular region defined by the 4 coordinates. Syntax: ------ POINT startx, starty, <endx, endy> where 'startx' and 'starty' is the location for the point and 'endx' and 'endy' define the region for randomization. Example: ------- POINT 50,50 will draw a point in the current drawing color at x=50, y=50. POINT 100,100,150,150 will draw a random point in the region defined by 100,100,150,150. Comments: -------- Transparent mode does not affect this command. PUTUP PUTUP Summary: ------- PUTUP allows you to place a clipping on the screen. PUTUP is similar to CFADE 0, but allows placement at any x and y location and supports transparent mode. Syntax: ------ PUTUP x ,y, <buffer number>, <delay> where 'x' and 'y' are the location where the lower left corner of the clipping will be placed, 'buffer number' is the clipping buffer number where the clipping you want to put up resides and delay is the time to wait after the putup in hundredths of a second. Example: ------- PUTUP 25,50,1,1000 will put the clipping in buffer 1 up on the screen at x=25, y=50 and then wait for time 1000 (10 seconds). Remember that the x and y coordinates correspond to the current video mode. Exceeding these coordinates may result in an error message. Comments: -------- Also see CFREE. RESETSCR RESETSCR Summary: ------- This command is used to reset the virtual screen back to display screen size after a PAN command with a larger-than-screen picture. Syntax: ------ RESETSCR Example: ------- RESETSCR will reset the virtual screen image. Comments: -------- Works only with EGA modes and PAN command. RETURN RETURN Summary: ------- This command causes execution of the current sub-program to halt and return control to the calling program. Syntax: ------ RETURN Example: ------- RETURN will return control to calling program. Comments: -------- Also see command GOSUB. SETCOLOR SETCOLOR Summary: ------- Setcolor is used to set the color palette registers in IBM EGA 16 color modes. On the EGA, there are 16 possible colors, called an 'index', and each of these color indices may be one of 64 color 'values'. SETCOLOR differs from CHGCOLOR in that SETCOLOR sets all 16 color indices at once. This is faster and is useful for animation effects. Syntax: ------ SETCOLOR color value 1, color value 2, ... color value 16 where 'color value n' lies in the range 0-63. Example: ------- SETCOLOR 3,32,23,53,12,11,10,21,35,2,4,8,30,40,61,63 will set the current palette registers to the 16 color values specified. Comments: -------- Remember, this only works in EGA 16 color modes and requires an Enhanced Color Display (ECD). TEXT TEXT Summary: ------- TEXT allows you to put-up a string of text in the font loaded with FLOAD in the current drawing color. Syntax: ------ TEXT x, y, string, <delay> where 'x' and 'y' is the location of the lower left corner of the first character in the string, 'string' is the string to put up and 'delay' is the time to wait after the put-up in hundredths of a second. Example: ------- TEXT 4,4,"This is a text string..." will put the string indicated between the quotes up at x=4, y=4, using the current drawing color. Comments: -------- The string to be put must be in double quotes. TRAN TRAN Summary: ------- TRAN allows you to set transparent mode on or off, and to specify which colors to make transparent. This is used for overlaying objects or floating objects across complex backgrounds. Syntax: ------ TRAN on/off, color1, color2,...colorn where 'on/off' specifies whether you want transparent mode turned on or off and color1-colorn indicate which colors you want to make transparent. Color1-colorn may have the values 0 to maxcolor where maxcolor is the highest color number available in your current video mode. Example: ------- TRAN on 2,14 will turn transparent mode on and make the colors 2 and 14 transparent. TRAN off will turn transparent mode off. Comments: -------- If you turn transparent mode on and off, the next time you turn it on, you must re-specify which colors you want to be transparent. Transparent does not work in EGA 16 color modes. VIDEO VIDEO Summary: ------- Video is used to set the video mode. Video should be used at the beginning of the GRASP text file. Video modes may be changed during the demo, but caution is advised. Damage may be done to a monitor if the wrong video mode is requested for your system. The default video mode is A, (see table below). Syntax: ------ VIDEO vidmode where 'vidmode' is one of the following... Maximum Picture Memory Vidmode Resolution # of Colors Requirement -------------------------------------------------------- 0 40x25 16 2K (IBM 40 column text) 1 80x25 16 4K (IBM 80 column text) 2 80x25 2 4K (IBM 80 column text) A 320x200 4 16K (IBM CGA) B 320x200 16 32K (IBM PCjr/STB) C 640x200 2 16K (IBM CGA) D 640x200 16/64 64K (IBM EGA) E 640x350 2 32K (IBM EGA monochrome) F 640x350 4 64K (IBM EGA) G 640x350 16/64 128K (IBM EGA) H 720x348 2 32K (Hercules monochrome) I 320x200 16 32K (Plantronics/AST CGP) J 320x200 16 32K (IBM EGA) These modes, (with the exception of the text modes) correspond to PCPAINT video modes. Example: ------- VIDEO G Will set up GRASP to use the high resolution mode of the EGA adapter in 16 out of 64 colors. Comments: -------- Memory requirement in the table above is the approximate amount of memory required for the buffer to hold EACH picture you load in for use. Also, pay attention to the size of the screen in each video mode. Attempting to FADE pictures other that this size may yield unpredictable results. The exception to this is when using the PAN command on an EGA. WAITKEY WAITKEY Summary: ------- This command instructs the demonstration or presentation to pause until a key is pressed, or until timeout value, if specified. If timeout occurs, conditional branching is allowed. Syntax: ------ WAITKEY <timeout>, <label> where 'timeout' is the time to wait before timeout in 100ths of a second and 'label' is the label to go to if timeout occurs. Example: ------- WAITKEY 600,myline will wait until a key is pressed, or until delay of 6 seconds. If delay of 6 seconds is reached, goto label 'myline'. Comments: -------- If no timeout is specified, WAITKEY will wait forever until a key is pressed. The key that is pressed to abort the wait is saved and may be tested by IFKEY. WINDOW WINDOW Summary: ------- This command is used to restrict a picture fade to a particular portion of the screen. The coordinates you pass are in pixels, but they are rounded to the nearest byte, or usually 8 pixels. Syntax: ------ WINDOW x,y,x1,y1 where 'x', 'y', 'x1' and 'y1' are the lower left and upper right corner of the window to set for clipping. Example: ------- WINDOW 40,40,100,160 will set the fade window to 40,40,100,160. The PFADE command will only fade that portion of the screen that lies in this region. Comments: -------- WINDOW has no effect on the CFADE command. ---------------------------------------------------------------------- Tips, Hints, Examples and Demo Programs Example Program #1 - Slide Show ------------------------------- A simple slideshow can be constructed by creating a grasp command file as follows: ; Slideshow demo for GRASP ; ; This program will load and display 4 pictures, alternating ; between fade #1 and fade #2, waiting for a count of 500 between ; each fade. ; video a ; set medium res 4 color CGA mode (this can ; be whatever mode you want to use) ; load pic1 ; load pic1 into buffer 1 fade 1 ; fade using fade number 1 waitkey 500 ; wait for a count of 500 ; load pic2 ; load pic2 into buffer 1 fade 2 ; but use fade #2 this time. waitkey 500 ; etc... ; load pic3 fade 1 waitkey 500 ; load pic4 fade 2 waitkey 500 ; exit ; quit the program Example Program #2 - How to animate using FLY --------------------------------------------- Let's say you have 2 clippings which are a flock of birds with wings up and wings down. To fly them across the screen, (from 0,160 to 300,160 issue the following sequence: tran on 3 ; turn transparent mode on ; (this assumes the background is color 3.) ; cload birds1,1 ; load in first clip cload birds2,2 ; load in second clip fly 0,160,300,160,3,4,1,2 ; fly 'em! ; tran off ; turn off transparent mode The parameters in the fly command are x1,y1,x2,y2,step(number of pixels between each putup),delay(time of delay between each putup), and list of clippings, in this case, 1 and 2. ---------------------------------------------------------------------- APPENDIX A - Command Summary Notes: ----- Each command's arguments (if any) are separated by commas or spaces, whichever is preferable. Comments begin at a semicolon and continue for the rest of the line. Line labels are up to 16 characters long and end with a colon,i.e.,<label>:. Subroutines can be nested up to 16 levels deep. There can be up to 16 levels of nesting in MARK,LOOP constructions. CAPITAL letters are the command name. It must be spelled correctly, but capitals are not required. LOWERCASE letters and numbers are parameters. You must specify all required parameters, (those not enclosed in <>), or you will get an error message indicating too few parameters. Command Summary: --------------- BOX x,y,x2,y2,<width> - draw a box CFADE #,x,y,<buffer>,<speed>,<delay> - fade a clipping to screen CFREE buffer,<buffer>,... - free up clipping buffer(s) CHGCOLOR from,to,<from,to>,... - EGA, change color index CIRCLE x,y,rx,<ry> - draw an ellipse CLEARSCR - clear screen CLOAD clipping filename,<buffer> - load a clipping COLOR color1,<color2> - set color 1 & color 2 EXEC program,<parameters> - execute program from GRASP EXIT - quit program FFREE - free the font buffer FGAPS <char_gap, space_gap> - set text gaps FLOAD character set filename - load a font FLOAT xs,ys,xe,ye,step,delay,clp1... - float clip across screen FLY xs,ys,xe,ye,step,delay,clp1... - fly clip across screen FSTYLE style - set text style GOSUB label - execute subroutine GOTO label - goto label IFKEY key,label - if key match, goto label LINE x,y,x2,y2 - draw line LINK textfile filename - link to another text file LOOP - loop to previous mark MARK loop count - mark for looping MODE border color,<palette> - CGA border & palette set NOISE freq1,freq2,duration - make some noise OFFSET x,y - set x and y offsets PALETTE buffer - EGA mode set palette PAN x0,y0,x1,y1,<buffer> - EGA pan from x0,y0 to x1,y1 PFADE #,<buffer>,<speed>,<delay> - fade a picture to screen PFREE buffer,<buffer>,... - free up picture buffer(s) PLOAD picture filename,<buffer> - load a picture POINT x,y,<x2,y2> - draw a point PUTUP x,y,<buffer>,<delay> - put a clip to screen @ x,y RESETSCR - reset screen to default RETURN - return from subroutine SETCOLOR c1,c2,c3...c16 - EGA mode set 16 colors TEXT x,y,"some text",<delay> - put up text @ x,y TRAN on/off, color - transparent mode on/off VIDEO vidmode - set video mode WAITKEY <timeout>, <label> - wait for a keypress WINDOW x0,y0,x1,y1 - set clip window APPENDIX B - Fade Table There are 25 fades in GRASP which must be called by number. All fades work on graphics screens, graphics screens in a window, clippings and text screens. This list is also accessable by pressing F3 while in the GRASP editor. Fade # Description ------ ------------------------------------------------------- 0 Quick snap wipe 1 Horizontal left to right wipe 2 Horizontal right to left wipe 3 Horizontal edge to center wipe 4 Horizontal center to edge wipe 5 Horizontal 1 pass filter wipe - both sides simultaneously 6 Horizontal 2 pass filter wipe - from left, then from right 7 Horizontal halves wipe - left to right, then right to left 8 Horizontal halves wipe - left and right simultaneously 9 Vertical top to bottom wipe 10 Vertical bottom to top wipe 11 Vertical edge to center wipe 12 Vertical center to egde wipe 13 Vertical filter wipe, top and bottom simultaneously 14 Vertical halves wipe, top and bottom simultaneously 15 Vertical halves wipe, left down, right up 16 Vertical quarters wipe 17 Vertical fingers wipe 18 Vertical fingers/filter combination wipe 19 Slither from top to bottom 20 Sparkle fade (random) 21 Diagonal wipe 22 Aperature dissolve - edge to center 23 Aperature dissolve - center to edge 24 Clockwise clock dissolve 25 Double slant dissolve APPENDIX C - Error Messages The following is a list of messages you may get while executing GRASP and some of their causes and solutions. MOST COMMON ERRORS: I. The most common error is not a grasp program error but a system error. The screen will clear, and you will get an error like External Memory allocation overflow, xxxxk requested, yyyyk free. This means that you have tried to load a picture or clipping that is too large for the memory you have left. There are several fixes for this problem. 1) Buy more memory. EGA 16 color demos usually take most of a 640K machine 2) Check your code and use PFREE, CFREE and FFREE to clean up memory when you are through using particular pictures, clippings and fonts. See the section of the manual on these commands. 3) Use the special parameter, ',1' on clipping loads that don't make the shifted copies. In order to be able to PUTUP a clipping at any single-pixel coordinate, GRASP needs to make up to 8 shifted copies of the clipping. If you are going to be using CFADE or putting it up at a byte boundary, then the shifted copies aren't necessary. You can keep them from being generated by typing: CLOAD clip,1,1 ;note the extra ',1' If you do specify the extra parameter, and you try to put up the clipping at a non-byte boundary, no putup will occur. Remember, FLY, FLOAT and PUTUP can put clippings at any coordinate. CFADE can only putup at a byte boundary. If none of the above three work, then call the GRASP and PCPAINT BBS for more advice. II. System Errors The following is a list of the GRASP system errors that you may encounter. These will appear on the top of the screen while running your demo along with a line number where the error occurred. When you press a key, you will be returned to that line in your program. If you get the error while running under the runtime version, the program will stop. DUPLICATE LABEL - You have used the same label name more than once in your demo and GRASP is confused. ERROR IN LOOP COUNT - Loop count must be a positive number. This error occurs if a negative number was specified. ERROR IN NAME - You have used an invalid character in a filename, or the file GRASP was trying to load was not found. ERROR IN PACKED CLIPPING - sometimes, clippings may be trashed or someone tries to load some other file with a .CLP extension. If GRASP does not recognize a clipping as being a valid clipping file, you will get this message. ERROR IN XCOORD - The Y-coordinate lies off the screen. This may occur after an OFFSET command. If you specify 0 for the Y coordinate, but Y offset is set to -5, you will get this error. ERROR IN YCOORD - The Y-coordinate lies off the screen. This may occur after an OFFSET command. If you specify 0 for the Y coordinate, but Y offset is set to -5, you will get this error. ERROR LOADING FONT - GRASP doesn't recognize the font you are trying to load. Also could be too large for memory or hardware error during load. ERROR LOADING PICTURE - GRASP doesn't recognize the picture you are trying to load. Also could be hardware error during load. ERROR LOADING TEXT - GRASP doesn't recognize the text file you are trying to link to. Also could be hardware during load. ILLEGAL ARGUMENT(S) - One of the arguments for the current command is invalid. Examples are invalid video mode, etc. ILLEGAL BUFFER - You have specified a buffer number that is outside of valid range. Buffers are 1-16 for pictures and 1-128 for clippings. Also may get this when an error occurs trying to allocate a new buffer during load. ILLEGAL COLOR - You have specified an invalid color number for this video mode. ILLEGAL FADE - You have specified an invalid fade number. Valid fades are 0-25. ILLEGAL PALETTE - You have specified an invalid palette number for CGA 4 color mode. Valid palettes are 0-5. ILLEGAL SPEED - You have specified an invalid speed for a fade. Valid speeds are 0-10000. INVALID FONT STYLE - You have specified an invalid font style number. Valid styles are 0-6. INVALID GAP VALUE - You have specified an invalid GAP value. Range is 0-255. LABEL NOT FOUND - You have tried to reference a label which was not previously defined. MEMORY ERROR - When trying to allocate the memory for your GRASP command file, an error was encountered. Usually only happens when a command file is too large. NOT ENOUGH ARGUMENTS - Certain commands require a minimum number of arguments. You need to specify some more. THIS COMMAND REQUIRES AN EGA - Just like it says, this particular command requires an EGA card and EGA video mode to operate. TOO MANY LOOPS - You have nested your loops deeper than the maximum, which is 16, or you have more loop commands that mark commands. TOO MANY MARKS - You have nested your loops deeper than the maximum, which is 16, or you have more mark commands than loop commands. UNKNOWN COMMAND - GRASP found something that was not a comment, not a label and couldn't recognize as a valid command. Check your spelling. APPENDIX D - Picture Swap Line There is a public domain electronic bulletin board which operates 24 hours a day with the sole purpose of providing a method by which users of PCPAINT and GRASP may exchange pictures, clippings, fonts, effects and ideas. This help eliminate the extra cost of providing artwork for many of the GRASP demos you may want to create. The most current version of GRASP will be avaliable this system. All uploads and downloads are free and may be used by anyone. We encourage you to contribute any artwork you feel could be used by someone else. Of course there will be proprietary artwork you either pay to have developed, or need to keep confidential. But your discards may be another's joy... The BBS is located in Costa Mesa, California, and the number is *** (714) 545-8100 *** You will be limited to 1 hour of use per day. We suggest that you use 1200 or 2400 baud modems set at 8 bits, 1 stop bit, no parity. You will be transferring binary files so the 8 bit mode is a must. There are several utility programs you will want to download first which allow you to squeeze and unsqueeze the pic files so that they will not take as much time to upload and download. You will find them in the UTILITY file area. Thanks in advance for your support and contributions to the board. APPENDIX E - GRASP Order Form GRASP is distributed in the USEware format. If you are going to USE it, please check the appropriate box below and enclose a check or purchase order. If you find the program unUSEable, please drop us a line telling us why. If you pay for the program by sending in this registration form with a check or money order, you will be added to our mailing list and be kept notified of new releases and new utilities. ------------------------------------------------------------------ Single-User Order Form ====================== If you are going to pay for less than 50 copies, use this form. The single user price is $50.00. California residents please add 6% sales tax. You must pay for EACH copy you plan to use. Full Name:__________________________ ___ Copies @ $50.00=_________ Address :__________________________ 6% Sales Tax =_________ :__________________________ Total Enclosed =_________ City, St.:_________________ _____ Zip:_________________ ------------------------------------------------------------------ Corporate Site License Order Form ================================= If you are going to be using in excess of 50 copies of GRASP within your company at one site, (5 mile radius from licensing party), you need only pay for the first 50 copies. You may then make and distribute to your employees an unlimited number of copies of the software and manual. We have 45 day billing if you include a P.O. number instead of a check or money order. Primary Corporate Contact for updates, etc.: Full Name :_________________________ 50 Copies @ $50.00 = $2500.00 Address :_________________________ 6% Sales Tax =_________ :_________________________ Total Enclosed =_________ Department:_________________________ P.O. Number:________________ City, St. :_________________ _____ Zip:_________________ Authorized Signature:______________________________ Date:_________ ------------------------------------------------------------------ ++--------------------------------------------------------------------- Things fixed or changed since 3.1a ---------------------------------- 1) PCX support should be completed. Included 256 color. Files should be identical to PCX output. 2) PFADE should work like PFADE 0 if a window is used. 3) Default mode (text) should clear screen in GRASPRT. *4) DLOAD, DFREE and PUTDFF should be added to GRASP. DLOAD defaults to buffer 1 like CLOAD and PLOAD and FLOAD PUTDFF BUFNUM DELAY BEGIN END XPOS YPOS BUFNUM defaults to 1 DELAY defaults to 0 BEGIN defaults to 0 END defaults to BEGIN is BEGIN is given, else defaults to last frame XPOS defaults to 0 YPOS defaults to 0 *5) STB VGA/EM card isn't being reset to text mode after quit of Pictor. *6) Pictor needs to allow CUT, COPY, PASTE, INVERT while in Change Colors box. This applies to the colors that lie between left and right button color. *7) Bug in MOVE command in GRASP where it doesn't hide the mouse cursor. *8) 80386 bug in moving large regions in Pictor, GRASP. 9) For PFADEs and CFADEs (ALL of them!) the lower left corner of the buffer should align with the lower left corner of the window unless altered with the position command. This means we should have some sort of position for CFADE. Perhaps OFFSET? *10) ERRORLEVEL is asigned to a key after an EXEC so IFKEY can test for it. *11) SPREAD 1,2 used to set palette 1 then spread to palette 2. Now, it works properly where it just figures the differences and does the spread. This allows very nice complicated operations previously impossible. ++--------------------------------------------------------------------- The formats of GRASP animation files. By George Phillips <phillips@cs.ubc.ca> Distribute this freely, but give credit where credit is due, eh? Version: Jan. 19,1991 GRASP is an animation system particular to the IBM PC world. It consists of a program to create animations and a run-time environment for displaying them. The most common form these animations take is ".GL" archives which may be displayed on an IBM-PC with a program called GRASPRT.EXE. This document describes what I have been able to decipher about the format of ".GL" archives and the files contained within. It should be useful to those attempting to write ".GL" animation players on other platforms. A ".GL" file is simply an archive file which contains images, fonts and a command file which tells GRASPRT what to do. These various files have standard extensions to denote their contents: .txt - A command file; usually there is only one of these per archive. .pic - An image. .clp - An image but without a colour map. .set or .fnt - A font containing character glyphs. It should be noted that the GL archive is of no particular importance; all the archived files could exist as ordinary files and the animation should still work. Any GL player should be able to operate both from an archive or from ordinary files. File Formats Most of the data in GL files can be adequately described as a stream of bytes which is practically universally understood. Some fields contain 2-byte and 4-byte integers. I'll refer to these as "words" and "long words" and they are all stored in little-endian format. So if we have 4 consecutive bytes, b1, b2, b3 and b4, the word at b1 is (b1 + b2 * 256) and the long word at b1 is (b1 + b2 * 256 + b3 * 256 * 256 + b4 * 256 * 256 * 256). Since this information was gathered by example, the purpose of some header fields and commands may not be known. I've marked unknown fields with question marks and have tried to put question marks and other warnings about descriptions which are guesses. GL Archives (.gl) A GL archive begins with a directory listing the files in the archive which is followed by the data for each file. +-- Directory Header | dir length (word) number of bytes in the directory header | +-- File Entry (17 bytes per, (dir length) / 17 of them) | | offset (long word) Position of file data as an offset from | | the beginning of the archive | | name (13 bytes) File name, null padded. | +-- +--- File data area | +-- File Data | | length (long word) Size of the file | | data (bytes) the file's data (surprise!) | +-- +--- Font Files (.fnt or .set) These are very simple; first a short header describing the size of the characters in the font and what byte values correspond to each glyph followed by the glyph data. +-- Font Header | length (word) length of the entire font file | size (byte) number of glyphs in the font file | first (byte) byte value represented by the first glyph | width (byte) width of each glyph in pixels | height (byte) height of each glyph in pixels | glyphsize (byte) number of bytes to encode each glyph +-- Glyph Data | glyph first | glyph first + 1 | ... | glyph first + size - 2 | glyph first + size - 1 +-- Each glyph is stored almost exactly as you would expect a raw PBM file to contain it except that a '0' bit means black and a '1' bit means white. In other words, row major order, each line padded to end on a byte boundary, most significant bit is leftmost. Image Formats (.pic and .clp) These consist of a header containing the usual image information followed by blocked, run-length encoded image data. +-- Image Header (17 or 19 bytes) | magic? (byte) magic number? Always is 0x34 or 0x12 | width (word) width of image in pixels | height (word) heigh of image in pixels | ???? (4 bytes) unknown | bpp (byte) bits per pixel (only seen 1 or 8) | type (byte) image type, either 'L' or 'C' | flags (byte) if (flags & 4) then image has colourmap | ? (byte) unknown | extend (byte) extended header byte (if != 0, header | has 2 more bytes) 1/2? | ? (byte) unknown | ?? (2 bytes) header extension if extend != 0 +-- Colour Map ((1 << bpp) * 3 bytes, only if flags & 4 == 4) | +-- Colour Map entries (as many as indicated by bpp) | | R (byte) red intensity, 0 - 63 \ | | G (byte) green intensity, 0 - 63 + entry 0 | | B (byte) blue intensity, 0 - 63 / | +-- | ... +-- Image Data | blocks (word) number of blocks of data | +-- Data Block (blocks of them) | | length (word) length of data block, including header | | bufsize (word) buffer size needed to hold all the | | uncompressed data in this block | | esc (byte) the escape code in this block | | data (length - 5 byte) run-length encoded data | +-- +-- The run-length encoding is byte oriented and follows these rules: - characters other than "esc" (see data block header) are literal - esc n c means repeat c n times (1 <= n <= 255) - esc 0 len(word) c means repeat c len times If bpp=1, then the resulting data stream is interpreted as it is with font glyphs (i.e., msb is left, pad to bytes, row first, etc). If bpp=8, then each byte in the data stream is an index into the colour map. If no colour map is available, the map to use can only be discovered by running through the command file. I've only seen images with bpp=1 and bpp=8 and they it always works out that either bpp=1 and type=C or bpp=8 and type=L. The type=C corresponds to CGA graphics which are mostly monochrome and 640 x 200 (so the aspect ratio is funny). Type=L is colour graphics, prob. VGA and usually 320 x 200. Notice that the colour maps have only 6 bits, the same as VGA's digital to analog converters. ".pic" files always have colour maps, ".clp" files never do. It seems that you can be lazy with your run-length decoding code; I've never seen a full sequence appear across a data-block boundary (encoders should probably not let that happen). The amount of uncompressed data in a block never seems to exceed 8192 bytes. Much of the header information is mysterious. Note that the header extension field is a guess and that there are other consistent possibilities (e.g., the extension field is a length byte or even part of a length word). Only type=C images seem to have the extension. Maybe the extra information is supposed to be used in video mode operating system calls on the PC? What made this part easier was the existence of a PC-based program which converts ".pic" files into GIF files. Its called "cvt2gif" and can be found on wuarchive.wustl.edu:/mirrors/msdos/gif/cvt2gif.zip. Those wishing to enhance the format descriptions would do well to get a copy. I did notice that bpp=1 images are not necessarily black and white but could be black and some other colour as selected from the CGA pallette. I doubt the distinction will make much difference to the animation, but if you really want to do it right... Command File (.txt) The command file looks like a typical script file with the lines delimited by carriage returns, line feeds or both. Any text following ';' on a line is a comment. Text followed by a colon is used to indicate a label (much like most assemblers). Commands consist of a keyword followed by a list of comma separated arguments. The input is case-insensitive except for arguments containing text to display (which are in double quotes). The basis of the command language seems to be what I call picture and clip registers, of which there are 16 of each. A few commands will load a picture (or clip) from a file into a register. Other commands then reference the register numbers to display the pictures or get colour maps from them. It seems that the colour map from a picture (.pic) is installed into the hardware and this is where the colour maps for the clips (.clp) come from. I assume that I am missing a lot of commands, but most notably I believe there should be more primitive drawing commands. Many of the commands seem to have a delay argument associated with them. This seems reasonable as control over time in an animation is important. I may have been over-zealous in looking for delays. The actual time units of the delays is unknown. They are typically numbers < 100, so milliseconds are a likely candidate. Hundredths of a second are possible as well. Here is a list of commands. Optional arguments are enclosed in []. Ranges are possible in arguments (I've only seem them in fly) and take the form "n,-,m", (e.g., fly 0,0,10,10,1,1,1,-,16). * box x1,y1,x2,y2,colour? Draw a box with corners (x1, y1) and (x2, y2) in the colour given by the colourmap entry number. * cfade x,y,delay,img,[,?,?] Display a clip image img at (x, y) and wait for delay time units before proceeding. * cfree n Free up any memory associated with clip register n. * clearscr Clear the display (to the currently selected colour or black?). * cload name,num[,?] Load a clip image "name" into clip register num. If name does not have a .clp extension, it will be automatically appended. * color n Set the current colour to n. This at least seems to affect the text displaying commands. * exit Terminate the command file. * fload name Load the named font which becomes the font to be used when displaying text. ".fnt" is appended to name if necessary. * float x1,y1,x2,y2,step?,delay?,num Move the clip image (num) by displaying it at (x1,y1) and erasing it and displaying it every step pixels until (x2,y2). Delay delay time units in between steps. Or maybe something completely different, but the x1,y1,x2,y2 and num arguments are probably coordinates and a clip number. * fly x1,y1,x2,y2,step?,delay?,clip list Successively display the clip images from (x1,y1) to (x2,y2) with delay time units in-between. The clip list is just a bunch of clip numbers separated by commas (i.e., fly is varags). A range is likely to appear in the clip list. Often (x1,y1) == (x2,y2). * fstyle ?[,?] Presumably set up some parameters on how a font is displayed. * goto label Force flow of control to the given label. * loop Denotes the end of a mark loop. Continues the loop at the most recent mark if the loop hasn't finished. * mark n This pairs with the loop command and begins a for loop from 1 to n. One assumes that the interaction of mark, loop and goto is the same as for, next and goto in BASIC. That is, loops are dynamically scoped and you can jump in and out of them. Mark simply pushes a loop start onto the stack and loop examines whatever is on the top of the loop stack. * mode ? Modify the current video mode in some way. I haven't seen this often. * note freq,delay?,duration Play a musical note of the given frequency and duration and delay for delay time units afterward. * palette n Make the colour map from picture register n be the one to use. This probably installs it into the hardware so that when a clip is loaded there is no colour map to change. * pfade effect,pict[,delay?[,?,?]] Display the picture numbered pict on the screen. The effect number indicates what sort of special effect is used to display it. What the numbers mean I have no idea, but I know some of the effects. Each pixel loaded randomly, every even line then every odd line and so on. The delay parameter seems to make sense, but not always. The extra parameters could be those needed for some effects. Often they are large numbers. * pfree n Free up any memory associated with picture register n. * pload name,n Load picture "name" into picture register n. ".pic" is appended to name if necessary. * putup x,y,n Display clip register n at (x,y). * set retrace [on|off] Set is probably a general internal control variable changing command. What retrace is I have no idea, but it was set off then on around a fly statement. * spread ?,? Who knows, but the numbers used are probably picture register numbers. Maybe some kind of colourmap changing? * text x,y,"text",[delay?] Display the given text (enclosed in double quotes) at (x,y). The extra parameter is probably a display, but it could be the display colour or the background colour. Probably the display colour is that given by the color statement. * tran [on 0|off] No idea. Was used around some cload and float statements. * video mode Set the display mode to 'C' or 'L' (remember the image format types?). Usually the first statement in a command file. C almost certainly refers to CGA which is 640 x 200 monochrome and L almost certainly to VGA which (in their case) is 320 x 200 x 256. * waitkey [[delay[,label]] Wait up to delay units for the user to press a key (or forever if no delay time is given). If the user presses a key and the label argument is present, transfer control to that label. * window x1,y1,x2,y2,? Some kind of display control. Probably a clipping window with appropriate coordinate translation (i.e., (0,0) becomes (x1,y1)). This document was created by looking hard at a number of GL files, using cvt2gif to help decipher the image file format and looking at 1 or 2 animations on an RS-6000 running a PC emulator and using grasprt. cvt2gif was very useful; grasprt under the PC emulator was painfully slow at times and didn't help my understanding much. I've never even gotten close to a copy of the program for creating and editing GL files. If you find out more about GL files, send me the changes so I can extend this document. Feel free to include this as supplementary documentation if you write a GL player. Finally, here are some projects which could help find out more about GL files: - Get cvt2gif and feed it small variations on .pic files to decipher the meaning of the missing header fields. I may do this. - Alter control files on some animations and see what effects they have. Something easy would be to change the effect number on pfade statements (if that's what it is). I don't have the hardware to do this. - Look at the GRASP animation package and intuit what the commands mean by what control you have over generating animations. This is probably the easiest way to get information. I don't have GRASP, I don't know where to get it and I don't has a PC good enough to run it on. ++--------------------------------------------------------------------- PCPAINT/Pictor Page Format Description Format by John Bridges. Document by Microtex Industries, Inc. Revision Date: 2/9/88 Global Notes: ------------ PCPAINT 1.0 - Revision 1.0 was developed for Mosue Systems in 1984 supported only BSAVE files in CGA 4 color mode. In the space between the scan buffers was a string that read PCPAINT 1.0 followed by 2 bytes which were the pallete and border information for that picture. PCPAINT 1.5 - Revision 1.5 was the same as 1.0 except that it contained larger than screen images and also had a primative packing format. This was sold for so short a time that it won't be covered here. PCPAINT 2.0 thru Pictor 3.1 - This document describes these formats. The file description is identical for all revisions in this range. However, in PCPAINT 2.0, the bit-planes were packed together so that the pictures resembled a PCjr picture, or 4 bits per pixel, 1 bit plane. Starting with Pictor 3.0, the files were saved with the bitplanes separated. This takes a little more memory in some cases, but the speed in loading and saving was a desireable consideration. NOTE TO PROGRAMMERS: A good PCPAINT/Pictor file decoder will use the variables in the header to decode the image and thus be compatible with all formats since the October, 1985 release of PCPAINT 2.0. Also please note that PCPAINT/Pictor are stored from the bottom up. This is opposite that of most of the screen adapters it supports. This really causes no problem, but be aware that you should use a Y table to look up scan lines. In all PCPAINT/Pictor pictures, the scan lines are continuous. If a picture is to be displayed on a particular adapter, the programmer is responsible for using a y-table to properly interleave the lines if necessary. Also note that Pictor was designed for speed, so no inter-mode loading is possible. If you are writing applications that create Pictor images that you want to load into Pictor, you must remain mode dependent. Header - A full description of the file header information. offset type name description ------- ------- ------- ----------------------------------------------------- 0 word marker marker that is always 01234h 2 word xsize x size of page in pixels 4 word ysize y size of page in pixels 6 word xoff x offset into page where lower left hand corner of viewport is located (default of 0 is ok) 8 word yoff y offset into page where lower left hand corner of viewport is located (default of 0 is ok) 10 byte bitsinf bits 0-3 is the number of bits per pixel per bit plane and bits 4-7 is the number of bit planes (so 4 color cga mode would be 02h and 16 color ega would be 31h and plantronics 16 color would be 12h) 11 byte emark marker that is always a 0ffh 12 byte evideo single uppercase letter indicating which video mode this picture was created in, can default to 0. 0 - 40 col text 1 - 80 col text 2 - mono text 3 - 43 line text A=320x200x4 cga B=320x200x16 pcjr, stbplus, tandy 1000 C=640x200x2 cga D=640x200x16 ega E=640x350x2 ega F=640x350x4 ega G=640x350x16 ega H=720x348x2 hercules I=320x200x16 plantronics J=320x200x16 ega K=640x400x2 AT&T or Toshiba 3100 L=320x200x256 vga M=640x480x16 ega plus(video 7, tseng, paradise), vga N=720x348x16 Hercules InColor O=640x480x2 vga 13 word edesc extra information descriptor defines what is in the extra information that follows this header, 0=nothing 1=pallet (single byte) border (single byte)[CGA] 2=pcjr or non ECD 16 color registers (0-15), 1 byte each 3=EGA with ECD 16 color registers (0-63) 1 byte each 4=VGA 256 color info - 256 colors, 1 byte each rgb gun. 15 word esize size of extra information in bytes 17 byte edata[] the actual extra data the size which is defined by esize (at offset 15). 17+ esize word numblks the number of packed blocks in this file. if this is a zero, then data is unpacked. Structures - These C structures describe the header information. If the file is packed then what follows is a multi block packed file, otherwise (if the file is not packed, numblks=0) the actual data follows. Bit planes follow each other in the file and when packed each bit plane must start in a new packed block. Packed Block Description Packed block header 0PBSIZE dw ;Packed block size. The size of this block BSIZE dw ;Unpacked block size MBYTE db ;Unique marker byte. This is a byte that does not ; exist in the current unpacked block. If no unique ; byte exists, then pick one that is used rarely ; to avoid too much redundancy. Packed block data - variable size depending on whether 16 bit run is needed. MARKER db ;mark a run (this is where MBYTE goes) LENGTH db ;length of run. if 0, then look at BIGLEN BIGLEN dw ;16 bit run count (only exists if LENGTH==0) DATA db ;byte to fill run with Example 1 - a 320x200, 4 color, packed page file, of a white screen. dw 0x1234 ;marker dw 320 ;x size dw 200 ;y size dw 0 ;x offset dw 0 ;y offset db 02h ;2 bits per pixel and 1 bit plane db 0xff ;extra info flag db 'A' ;vidmode dw 1 ;extra area descriptor (pal and bord) dw 2 ;bytes in extra area db 2,0 ;pallet and border (extra information) dw 2 ;number of packed blocks ;first block dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0xff ;byte to fill run with ;second block dw 5+5 ;packed block size dw 7808 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 7808 ;16 bit run count db 0xff ;byte to fill run with Example 2 - a 640x350, 16 color, packed page file, of a red screen (color 4). dw 0x1234 ;marker dw 640 ;x size dw 350 ;y size dw 0 ;x offset dw 0 ;y offset db 31h ;bits per pixel and 1 bit plane db 0xff ;new extra info flag db 'G' ;vidmode dw 3 ;extra area descriptor (pal and bord) dw 16 ;bytes in extra area db 0,1,2,3,4,5,14h,7 db 38h,39h,3ah,3bh,3ch,3dh,3eh,3fh dw 16 ;number of packed blocks ;block 1 of first bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 2 of first bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 3 of first bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 4 of first bit plane dw 5+5 ;packed block size dw 3424 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 3424 ;16 bit run count db 0 ;byte to fill run with ;block 1 of second bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 2 of second bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 3 of second bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 4 of second bit plane dw 5+5 ;packed block size dw 3424 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 3424 ;16 bit run count db 0 ;byte to fill run with ;block 1 of third bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0xff ;byte to fill run with ;block 2 of third bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0xff ;byte to fill run with ;block 3 of third bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0xff ;byte to fill run with ;block 4 of third bit plane dw 5+5 ;packed block size dw 3424 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 3424 ;16 bit run count db 0xff ;byte to fill run with ;block 1 of fourth bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 2 of fourth bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 3 of fourth bit plane dw 5+5 ;packed block size dw 8192 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 8192 ;16 bit run count db 0 ;byte to fill run with ;block 4 of fourth bit plane dw 5+5 ;packed block size dw 3424 ;unpacked block size db 0 ;marker byte db 0 ;mark a run db 0 ;a 16 bit run count follows dw 3424 ;16 bit run count db 0 ;byte to fill run with Example 3 - For more detail lets consider a block that isn't all the same. Say the data consists of 30 2's, and 8, a 4, and 300 1's. ; the block would look like this dw 5+10 ;packed block size dw 332 ;30 + 1 + 1 + 300 bytes as above db ff ;what to mark a run with, ; because there are no ff's in our example. db ff ;mark a run db 30 ;8 bit run count db 2 ;byte to fill run with - 2 db 8 ;not a run marker, so must be data db 4 ;not a run marker, so must be data db ff ;mark a run db 0 ;means 16 bit run count follows dw 300 ;run count db 1 ;byte to fill run with - 1 The actual unpacked data that resides in memory consists 2 seperate sections. 1. The control structure: contains x size, y size, x offset, y offset, segment of bit mapped data, number of bits per pixel and number of additional bit planes. this information is kept in pcpaint's data segment. 2. The actual bit mapped data: contains the actual page image, mapped from bottom left (so bottom scan line is first). The data is contiguous within each bit plane, so scan line 1 follows scan line 0 directly. the page can and does cross segment boundires (a bit plane can be larger than 64k). each bit plane follows the previous but starts on a paragraph boundary, the printer driver will be passed the offset in paragraphs between bit planes and the number of additional planes. The bit planes start with bit 0, each additional plane is the next bit. ++--------------------------------------------------------------------- THE DATA TRANSFORMS FONT FORMAT Data Transforms, Inc. 616 Washington St. Denver, Colorado 80203 (303) 832-1501 Technical Support Contacts: Bob Van Arsdale Glenn Searfoss Steven Boker A Brief Background. Data Transforms' font library of over 200 different font styles (Fontpak Volumes 1 - 15, and Laser Fontpak volumes 1 & 2) was created by our IBM Fontrix graphics package. The font creation limits of the Fontrix Font Editor are 1 x 1 to 96 x 96 pixels and may be any alphanumeric, language, or symbol. Fontrix, written in C and Assembler, creates/saves images and fonts in a bit-mapped raster format. The Fontrix Font Format Definition. "Font1 Structure Definition" describes the standard font header of a Data Transform non-compressed font. Each font has a header that defines the font and points to the character bitmaps. Immediately following the font header is the character bitmap data. Character bitmaps are stored as scanrects in scanline order from top to bottom. Each scanline is stored bytewise left to right, left justified and rounded to byte length. Each byte is stored 8 bits per byte where MSB is the leftmost pixel. "Font2 Structure Definition" details the header information for a font compressed using a "bounding box~ data compression method. This method (see Figure 2) involves outlining a cell's "bit-on~ character data with the smallest box possible. Coordinates that position the "box" relative to the original character cell are saved in the font header. This compression method is automatic within the Data Transforms Font Editor when a font over 32 x 32 pixels in size is saved. The bounding box routine can run at up to 90% of the over-all compression efficiency of more computationally expensive compression algorithms. The actual character bits-on data is never compressed. Information regarding the bounding box (size, [x,y] position within the original cell, etc...) is kept for each character in a lookup table in the font header. Using this compression method on the character cell in Figure 1 (lower case "i~), the net gain in savings is 94% of the original character cell size. For Figure 3 (upper case "W~), the net savings is 31% of the original character cell size. The percentage in savings correlates to the discarded zero (bit off) data outside of the bounding box. The character data is never compressed; rather, the empty space outside of the bounding box is discarded. The analogy of a shrink-wrap bag can be used to illustrate. Imagine a character cell placed within a shrink-to-fit bag. The non-compressed cell is the unshrunk bag. Now shrink the bag until all edges contact the outer limits of bit-on data, forming a rectangular bounding box. For some characters, as in a lower case "i", this correlates to a major amount of shrinkage and the shrinkage correlates to saved data space, hence compression. An upper case "W" may fill the majority of a cell. In this instance minimal shrinkage will occur, with little or no saved data space. However, the overall net savings in data space for an entire font set will be great since few characters fill an entire cell. /* FONT1 STRUCTURE DEFINITIONS */ struct font1head { /* standard character font header */ unsigned char fnttype; /* font structure type: */ /* non-compressed type = 0x10 or compressed type = 0x14 */ char fntname[13]; /* font name -always followed with a ".set" extension */ unsigned char fntcheck; /* check digit - verifies a Data Transforms font */ /* non-compressed font = 0xba, compressed font = 0xdc */ unsigned char fntbase; /* baseline count (in pixels) from top to bottom, top = 0 */ unsigned char fnttotal; /* total characters in font:*/ /* limited to the lower 94 ASCII characters: 0x21 - 0x7E */ unsigned char fntstart; /* starting character */ unsigned char fntstatus;/* proportional or non-proportional: 0 = non-proportional */ unsigned char fnthsize; /* horizontal cell size in pixels */ unsigned char fntvsize; /* vertical cell size in pixels */ unsigned char fntbytes; /* number of horizontal bytes in the current cell */ unsigned char fntspaceh; /* space bar horizontal size in pixels */ unsigned char fntchargap; /* pixels between characters default */ unsigned char fntlfgap; /* pixels between linefeeds default */ int fntlength; /* total length of file */ unsigned char fntpitch; /* italics pitch (0 = none) */ /* bits 0 - 6 ... number of scanlines to skip */ /* bit 7 ... 0 = decrement xpos, 1 = increment xpos */ unsigned char fntinvert; /* 0 = dont invert, 1 = invert */ unsigned char fnthbold; /* number of overlapping bits horizontal */ unsigned char fntvbold; /* number of overlapping bits vertical */ unsigned char fnthmag; /* integral horizontal bit magnification */ unsigned char fntvmag; /* integral vertical bit magnification */ unsigned char fnthfract; /* fractional horizontal bit magnification */ unsigned char fntvfract; /* fractional vertical bit magnification */ unsigned char fntdirection; /* Print direction 0 = left to right, 1...3 = counterclock 1...3 */ unsigned char fntrot90; /* rotation 0 = up, 1...3 = counterclock 1...3 */ unsigned char fnthflip; /* horizontal flip 0 = no, 1 = yes */ unsigned char fntvflip; /* vertical flip 0 = no, 1 = yes */ unsigned char fntcolor; /* color of font */ /* bits 0 - 3 ... foreground color */ /* bit 0 ... strike black ribbon */ /* bit 1 ... strike blue ribbon */ /* bit 2 ... strike red ribbon */ /* bit 3 ... strike yellow ribbon */ /* bits 4 - 7 ... background color */ /* bit 4 ... strike black ribbon */ /* bit 5 ... strike blue ribbon */ /* bit 6 ... strike red ribbon */ /* bit 7 ... strike yellow ribbon */ unsigned char fntsubtype; /* subcategory type of this font */ /* 0 = normal font subtype */ /* 1 = equation roman font subtype */ /* 2 = equation symbol font subtype */ unsigned char fntunused[18]; /* unused bytes */ }; struct font1 { /* standard character font (type = 0x10) */ struct font1head fhd; /* font header */ char *fntcellptr[FONT1TOTAL + 1]; /* offsets from beginning of file to character bitmaps */ char fntcellwidth[FONT1TOTAL + 1]; /* cell widths if proportional */ }; /* FONT2 STRUCTURE DEFINITIONS */ struct font2 { struct font1head fhd2; /* font header */ unsigned int fnt2cellseg[FONT2TOTAL + 1]; /* array of segment pointers to characters */ int fnt2cellhsize[FONT2TOTAL + 1]; /* array of cell horizontal sizes in bits */ int fnt2cellhoffset[FONT2TOTAL + 1]; /* array of cell horizontal offsets in bits */ int fnt2cellhbytes[FONT2TOTAL + 1]; /* array of cell horizontal size in bytes */ int fnt2cellvsize[FONT2TOTAL + 1]; /* array of cell vertical sizes in bits */ int fnt2cellvoffset[FONT2TOTAL + 1]; /* array of cell vertical offsets in bits */ }; The data listed in the "struct font2~ portion of the (Font2) font structure above is defined as follows: * The font header is the same as described in the "struct font1head~ of the non-compressed font data format. * Font cell segments are an array of segment pointers to characters kept as offsets from the beginning of the font file. For example, if an array value for a character = 10, then the starting address of a character's "bounding box~ data = (the start of file address + sizeof (struct font2)) + (10 x 16), where 1 segment = 16 bytes. * The Horizontal size is the actual width in bits of the bounding box. * The Horizontal offset is the distance in bits from the left edge of the cell to the upper lefthand corner of the bounding box. * Horizontal bytes refers to the actual size in bytes of the interior of the bounding box. * The Vertical size is the actual height in bits of the bounding box. * The Vertical offset is the distance in bits from the top edge of the cell to the upper edge of the bounding box. ++--------------------------------------------------------------------- Technical Reference Manual Including Information For: Publisher's Paintbrush PC Paintbrush Plus PC Paintbrush ZSoft Corporation 450 Franklin Rd. Suite 100 Marietta, GA 30067 (404) 428-0008 IMAGE FILE (.PCX) FORMAT The information in this section will be useful if you want to write a program to read or write PCX files (images). If you want to write a special case program for one particular image format you should be able to produce something that runs twice as fast as "Load from..." in PC Paintbrush. Image files used by PC Paintbrush product family and FRIEZE (those with a .PCX extension) begin with a 128 byte header. Usually you can ignore this header, since your images will all have the same resolution. If you want to process different resolutions or colors, you will need to interpret the header correctly. The remainder of the image file consists of encoded graphic data. The encoding method is a simple byte oriented run-length technique. We reserve the right to change this method to improve efficiency. When more than one color plane is stored in the file, each line of the image is stored by color plane (generally ordered red, green, blue, intensity), As shown below. Scan line 0: RRR... GGG... BBB... III... Scan line 1: RRR... GGG... BBB... III... (etc.) The encoding method is: FOR each byte, X, read from the file IF the top two bits of X are 1's then count = 6 lowest bits of X data = next byte following X ELSE count = 1 data = X Since the overhead this technique requires is, on average, 25% of the non-repeating data and is at least offset whenever bytes are repeated, the file storage savings are usually considerable. The format of the file header is shown below. ZSoft .PCX FILE HEADER FORMAT Byte Item Size Description/Comments 0 Manufacturer 1 Constant Flag 10 = ZSoft .PCX 1 Version 1 Version information: 0 = Version 2.5 2 = Version 2.8 w/palette information 3 = Version 2.8 w/o palette information 5 = Version 3.0 2 Encoding 1 1 = .PCX run length encoding 3 Bits per pixel 1 Number of bits/pixel per plane 4 Window 8 Picture Dimensions (Xmin, Ymin) - (Xmax - Ymax) in pixels, inclusive 12 HRes 2 Horizontal Resolution of creating device 14 VRes 2 Vertical Resolution of creating device 16 Colormap 48 Color palette setting, see text 64 Reserved 1 65 NPlanes 1 Number of color planes 66 Bytes per Line 2 Number of bytes per scan line per color plane (always even for .PCX files) 68 Palette Info 2 How to interpret palette - 1 = color/BW, 2 = grayscale 70 Filler 58 blank to fill out 128 byte header All variables of size 2 are integers. Decoding .PCX Files First, find the pixel dimensions of the image by calculating [XSIZE = Xmax - Xmin + 1] and [YSIZE = Ymax - Ymin + 1]. Then calculate how many bytes are required to hold one complete uncompressed scan line: TotalBytes = NPlanes * BytesPerLine Note that since there are always an integral number of bytes, there will probably be unused data at the end of each scan line. TotalBytes shows how much storage must be available to decode each scan line, including any blank area on the right side of the image. You can now begin decoding the first scan line - read the first byte of data from the file. If the top two bits are set, the remaining six bits in the byte show how many times to duplicate the next byte in the file. If the top bits are not set, the first byte is the data itself, with a count of one. Continue decoding the rest of the line. Keep a running subtotal of how many bytes are moved and duplicated into the output buffer. When the subtotal equals TotalBytes, the scan line is complete. There will always be a decoding break at the end of each scan line. But there will not be a decoding break at the end of each plane within each scan line. When the scan line is completed, there may be extra blank data at the end of each plane within the scan line. Use the XSIZE and YSIZE values to find where the valid image data is. If the data is multi-plane BytesPerLine shows where each plane ends within the scan line. Continue decoding the remainder of the scan lines. There may be extra scan lines at the bottom of the image, to round to 8 or 16 scan lines. Palette Information Description EGA/VGA 16 Color Palette Information The palette information is stored in one of two different formats. In standard RGB format (IBM EGA, IBM VGA) the data is stored as 16 triples. Each triple is a 3 byte quantity of Red, Green, Blue values. The values can range from 0-255 so some interpretation into the base card format is necessary. On an IBM EGA, for example, there are 4 possible levels of RGB for each color. Since 256/4 = 64, the following is a list of the settings and levels: Setting Level 0-63 0 64-127 1 128-192 2 193-254 3 VGA 256 Color Palette Information ZSoft has recently added the capability to store palettes containing more than 16 colors in the .PCX image file. The 256 color palette is formatted and treated the same as the 16 color palette, except that it is substantially longer. The palette (number of colors x 3 bytes in length) is appended to the end of the .PCX file, and is preceded by a 12 decimal. To determine the VGA BIOS palette you need only divide the values read in the palette by 4. To access a 256 color palette: First, check the version number in the header, if it contains a 5 there is a palette. Second, read to the end of the file and count back 769 bytes. The value you find should be a 12 decimal, showing the presence of a 256 color palette. CGA Color Palette Information For a standard IBM CGA board, the palette settings are a bit more complex. Only the first byte of the triple is used. The first triple has a valid first byte which represents the background color. To find the background, take the (unsigned) byte value and divide by 16. This will give a result between 0-15, hence the background color. The second triple has a valid first byte, which represents the foreground palette. PC Paintbrush supports 8 possible CGA palettes, so when the foreground setting isbetween 0 and 255, there are 8 ranges of numbers and the divisor is 32. CGA Color Map Header Byte #16 Background color is determined in the upper four bits. Header Byte #19 Only upper 3 bits are used, lower 5 bits are ignored. The first three bits that are used are ordered C, P, I. These bits are interpreted as follows: c: color burst enable - 0 = color; 1 = monochrome p: palette - 0 = yellow; 1 = white i: intensity - 0 = dim; 1 = bright PC Paintbrush Bitmap Character Format The bitmap character fonts are stored in a particularly simple format. The format of these characters is as follows: Header (2 bytes) font width db 0a0h + character width (in dots) font height db character height (in dots) Character Widths (256 bytes) char widths db 256 dup(each char's width +1) Character Images (remainder of the file) The characters are stored in ASCII order and as many as 256 may be provided. Each character is left justified in the character block, all characters take up the same number of bytes. Bytes are organized as N strings, where each string is one scan line of the character. See figure 2. For example, each character in a 5x7 font requires 7 bytes. A 9x14 font uses 28 bytes per character (stored two bytes per scan line in 14 sets of 2 byte packets). Custom fonts may be any size up to the current maximum of 10K bytes allowed for a font fil e. Sample "C" Routines The following is a simple set of C subroutines to read data from a .PCX file. /* * This procedure reads one encoded block from the image file and stores * a count and data byte. * Result: * 0 = valid data stored * EOF = out of data in file */ encget(pbyt, pcnt, fid) int *pbyt; /* where to place data */ int *pcnt; /* where to place count */ FILE *fid; /* image file handle */ { int i; *pcnt = 1; /* safety play */ if (EOF == (i = getc(fid))) return(EOF); if (0xc0 == (0xc0 & i)) { *pcnt = 0x3f&i; if (EOF == (i = getc(fid))) return(EOF); } *pbyt = i; return(0); } /* * Here's a program fragment using encget. This reads an entire file and * stores it in a (large) buffer, pointed to by the variable "bufr". * "fp" is the file pointer for the image */ while (EOF != encget(&chr, &cnt, fp)) for (i = 0; i ~ *bufr++ = chr; The following is a set of C subroutines to write data to a .PCX file. /* This subroutine encodes one scanline and writes it to a file */ encLine(inBuff, inLen, fp) unsigned char *inBuff; /* pointer to scanline data */ int inLen; /* length of raw scanline in bytes */ FILE *fp; /* file to be written to */ { /* returns number of bytes written into outBuff, 0 if failed */ unsigned char this, last; int srcIndex, i; register int total; register unsigned char runCount; /* max single runlength is 63 */ total = 0; last = *(inBuff); runCount = 1; for (srcIndex = 1; srcIndex inLen; srcIndex++) { this = *(++inBuff); if (this == last) { runCount++; /* it encodes */ if (runCount == 63) { if (!(i=encput(last, runCount, fp))) return(0); total += i; runCount = 0; } } else { /* this != last */ if (runCount) { if (!(i=encput(last, runCount, fp))) return(0); total += i; } last = this; runCount = 1; } } /* endloop */ if (runCount) { /* finish up */ if (!(i=encput(last, runCount, fp))) return(0); return(total + i); } return(total); } /* subroutine for writing an encoded byte pair (or single byte if it doesn't encode) to a file */ encput(byt, cnt, fid) /* returns count of bytes written, 0 if err */ unsigned char byt, cnt; FILE *fid; { if(cnt) { if( (cnt==1) && (0xc0 != (0xc0&byt)) ) { if(EOF == putc((int)byt, fid)) return(0); /* disk write error (probably full) */ return(1); } else { if(EOF == putc((int)0xC0 | cnt, fid)) return(0); /* disk write error */ if(EOF == putc((int)byt, fid)) return(0); /* disk write error */ return(2); } } return(0); }